Monte Library Private Knowledge Base Library 中文

Original Note

4.2 Preparing Software for Reuse and Release

  • self_study_notes
  • Original Note
  • Updated: unknown
Source Collection
self_study_notes
Source Path
self_study_notes/python software/Collaborative Development for Reuse/整理版/4.2 Preparing Software for Reuse and Release.md
Type
Original Note
Updated At
unknown

4.2 Preparing Software for Reuse and Release（整理版）

原始笔记: 4.2 Preparing Software for Reuse and Release.md 原始教程: 4.2 Preparing Software for Reuse and Release created: 2026-07-30 10:30 整理说明: 本版本只整理原笔记已有的软件复用层级、README、CI badge、license、Git tag 与 Semantic Versioning；保留命令及关键参数解释，并对已发布 tag 的修改补充安全边界。

内容简要概括

可复用软件不仅要能重复产生结果，还要让其他人能够理解、安装、使用和修改。README、CI 状态、license 和清晰的发布 tag 共同提供使用入口、质量信号、法律边界与稳定版本标识；Semantic Versioning 则用版本号表达兼容性变化。

软件复用、README、CI badge、LICENSE、MIT、Git tag、annotated tag、Semantic Versioning、MAJOR.MINOR.PATCH、软件发布、可复现性、版本管理

目录

1. 软件复用的五个层级

软件的可复用程度可以按以下层级理解：

  1. 可重新运行（Re-runnable）：代码能够再次执行，但不保证结果一致；
  2. 可重复（Repeatable）：多次运行能够得到相同结果；
  3. 可复现（Reproducible）：使用相同软件版本和输入数据，可以重新生成已发布的研究结果；
  4. 可复用（Reusable）：软件容易使用、理解和修改；
  5. 可复制实现（Replicable）：其他人能够根据论文描述重新实现算法，并用原始实现消除描述中的歧义。

后一个层级通常以前面的层级为基础。研究软件至少应以 Reusable 为目标：

  • Reproducible 关注能否重新得到相同研究结果；
  • Reusable 进一步关注其他人能否理解、运行、修改和扩展软件。

2. README 的最低结构

README 是新用户理解项目的第一入口。它至少应回答：

  • 项目解决什么问题；
  • 软件有哪些主要功能；
  • 运行前需要哪些依赖；
  • 如何安装和执行；
  • 如何贡献和获取帮助；
  • 如何引用以及使用什么许可证。

2.1 可复用 README 模板

# 项目名称

一句话描述项目解决什么问题。

## Main Features

- 主要功能 1
- 主要功能 2

## Prerequisites

- 运行时依赖
- 测试或开发依赖

## Installation

安装步骤。

## Usage

最基本的使用示例。

## Contributing

如何提交 Issue、代码和 Pull Request。

## Getting Help

问题反馈和获取帮助的渠道。

## Credits

贡献者和致谢。

## Citation

学术引用方式。

## License

许可证说明。

README 中的示例应尽量短小、可复制，并与当前发布版本一致。依赖列表需要区分普通用户运行软件所需的依赖，以及只在测试和开发时使用的可选依赖。

3. 在 README 中展示 CI Badge

GitHub Actions 可以为 workflow 提供 SVG 状态徽章，用于显示目标分支最近一次 CI 是否成功。

![Continuous Integration build in GitHub Actions](https://github.com/<your_github_username>/python-intermediate-inflammation/actions/workflows/main.yml/badge.svg?branch=main)

Markdown 图片语法是：

![替代文字](图片地址)
  • 方括号中的文字是图片无法加载时显示的替代文本；
  • 圆括号中的 URL 是 GitHub 动态生成的 SVG 图片地址。

3.1 Badge URL 的组成

https://github.com/<your_github_username>/
python-intermediate-inflammation/
actions/workflows/main.yml/
badge.svg?branch=main
部分 含义
<your_github_username> GitHub 用户名或组织名
python-intermediate-inflammation 仓库名称
actions/workflows/main.yml workflow 配置文件
badge.svg 请求 SVG 状态徽章
branch=main 展示 main 分支的 workflow 状态

Badge 是当前 CI 状态的快速信号，但不能代替 README 中的测试说明或发布验证记录。

4. 添加软件许可证

许可证明确其他人可以如何使用、修改和分发软件。没有许可证并不等于允许自由使用，因此准备复用和发布时应明确选择并提交许可证。

4.1 获取 MIT License 模板

安装 GitHub CLI 后，可以通过 GitHub API 获取 MIT 模板：

gh api licenses/mit --jq .body > LICENSE
  • gh api licenses/mit：请求 GitHub 的 MIT license API；
  • --jq .body：只提取响应中的正文；
  • > LICENSE：把正文写入仓库根目录的 LICENSE 文件。

打开 LICENSE，将：

Copyright (c) [year] [fullname]

替换为真实年份和权利人：

Copyright (c) 2026 Your Name

4.2 提交许可证

git add LICENSE
git commit -m "docs: add MIT license"
git push

README 中应同时说明：

## License

This project is licensed under the MIT License.
See [LICENSE](LICENSE) for details.

4.3 在 pyproject.toml 中声明

现代 Python 项目可以在 pyproject.toml 中记录 license：

[project]
license = "MIT"
license-files = ["LICENSE"]
  • MIT 是 SPDX identifier；
  • license-files 确保构建的发布包包含许可证文件。

5. 使用 Git Tag 标记发布

Git tag 是指向特定 commit 的人类可读名称：

v1.0.0 → commit 2df4bf...

分支会随着新提交移动，而发布 tag 通常应保持不变：

main：A → B → C → D
              ↑
           v1.0.0

这里 main 可以继续前进到 D，但 v1.0.0 仍然指向 C。

5.1 查看本地 Tag

git tag

该命令列出本地仓库中的所有 tag。

5.2 创建 Annotated Tag

git tag -a v1.0.0 -m "Version 1.0.0"
  • -a：创建 annotated tag；
  • v1.0.0：tag 名称；
  • -m：写入 tag 说明；
  • 未指定 commit 时，默认标记当前 HEAD。

Annotated tag 会保存创建者、创建时间、说明和目标 commit，适合正式发布。

5.3 查看 Tag 内容

git show v1.0.0

输出通常包括：

  • tag 名称、Tagger、时间和说明；
  • tag 指向的 commit；
  • 该 commit 的提交信息和 diff。

5.4 推送 Tag

普通分支推送不会自动发布本地 tag：

git push origin main

单独推送准备发布的 tag：

git push origin v1.0.0

也可以推送所有本地 tag：

git push origin --tags

实际项目中优先推送指定 tag，避免把实验或临时 tag 一并上传。

6. Semantic Versioning

Semantic Versioning 使用：

MAJOR.MINOR.PATCH\text{MAJOR.MINOR.PATCH}

例如：

1.4.2
位置 何时增加 示例
MAJOR 产生不兼容的 API 修改 1.2.3 → 2.0.0
MINOR 向后兼容地增加功能 1.2.3 → 1.3.0
PATCH 向后兼容地修复问题 1.2.3 → 1.2.4

预发布版本可以写成：

1.0.0-alpha.1
1.0.0-beta.1
1.0.0-rc.1

其中 rc 表示 release candidate。

版本号变化向用户传达更新风险：版本号不应只作为装饰，每次重新发布都应使用新的版本。

7. 已发布 Tag 的安全边界

本地、尚未推送的 tag 可以重新指向目标 commit：

git tag -f v1.0.0 main

-f 会覆盖本地同名 tag，因此执行前应先用 git show v1.0.0 检查旧目标。

对已发布版本，推荐修复后创建新版本，例如：

git tag -a v1.0.1 -m "Version 1.0.1"
git push origin v1.0.1

只有在明确确认无人依赖旧 tag、团队已经协调并核对远程目标时，才考虑更正错误 tag；这应作为受控的仓库维护操作，而不是常规发布流程。

Evidence-backed relations

Source Note · Same Topic

切换到中文